# eric7.Plugins.CheckerPlugins.CodeStyleChecker.DocStyle.DocStyleChecker

Module implementing a checker for documentation string conventions.

### Global Attributes

None

### Classes

DocStyleChecker | Class implementing a checker for documentation string conventions.
DocStyleContext | Class implementing the source context.

### Functions

None

## DocStyleChecker

Class implementing a checker for documentation string conventions.

### Derived from

CodeStyleTopicChecker

### Class Attributes

Category
Codes

### Class Methods

None

### Methods

DocStyleChecker | Constructor
__checkBackslashes | Private method to check, that all docstrings containing backslashes are surrounded by raw triple double quotes.
__checkBlankAfterLastParagraph | Private method to check, that the last paragraph of docstrings is followed by a blank line.
__checkBlankAfterSummary | Private method to check, that docstring summaries are followed by a blank line.
__checkBlankBeforeAndAfterClass | Private method to check, that class docstrings have one blank line around them.
__checkClassDocstring | Private method to check, that all public functions and methods have a docstring.
__checkEndsWithPeriod | Private method to check, that docstring summaries end with a period.
__checkEricBlankAfterSummary | Private method to check, that docstring summaries are followed by a blank line.
__checkEricDocumentationDeprecatedTags | Private method to check the use of deprecated documentation tags.
__checkEricDocumentationIndent | Private method to check the the correct indentation of the tag lines.
__checkEricDocumentationSequence | Private method to check, that method docstring follows the correct sequence of entries (e.g.
__checkEricEndsWithPeriod | Private method to check, that docstring summaries end with a period.
__checkEricException | Private method to check, that docstrings contain an @exception line if they raise an exception and don't otherwise.
__checkEricFunctionArguments | Private method to check, that docstrings contain an @param and/or @keyparam line for each argument.
__checkEricNBlankAfterLastParagraph | Private method to check, that the last paragraph of docstrings is not followed by a blank line.
__checkEricNoBlankBeforeAndAfterClassOrFunction | Private method to check, that class and function/method docstrings have no blank line around them.
__checkEricQuotesOnSeparateLines | Private method to check, that leading and trailing quotes are on a line by themselves.
__checkEricReturn | Private method to check, that docstrings contain an @return line if they return anything and don't otherwise.
__checkEricSignal | Private method to check, that docstrings contain an @signal line if they define signals and don't otherwise.
__checkEricSummary | Private method to check, that method docstring summaries start with specific words.
__checkEricYield | Private method to check, that docstrings contain an @yield line if they return anything and don't otherwise.
__checkFunctionDocstring | Private method to check, that all public functions and methods have a docstring.
__checkImperativeMood | Private method to check, that docstring summaries are in imperative mood.
__checkIndent | Private method to check, that docstrings are properly indented.
__checkModulesDocstrings | Private method to check, if the module has a docstring.
__checkNoBlankLineBefore | Private method to check, that function/method docstrings are not preceded by a blank line.
__checkNoSignature | Private method to check, that docstring summaries don't repeat the function's signature.
__checkOneLiner | Private method to check, that one-liner docstrings fit on one line with quotes.
__checkReturnType | Private method to check, that docstrings mention the return value type.
__checkSummary | Private method to check, that docstring summaries contain some text.
__checkTripleDoubleQuotes | Private method to check, that all docstrings are surrounded by triple double quotes.
__getArgNames | Private method to get the argument names of a function node.
__getSummaryLine | Private method to extract the summary line.
__getSummaryLines | Private method to extract the summary lines.
__parseClasses | Private method to extract top-level classes.
__parseContexts | Private method to extract a context from the source.
__parseDocstring | Private method to extract a docstring given `def` or `class` source.
__parseFunctions | Private method to extract top-level functions.
__parseMethods | Private method to extract methods of all classes.
__parseModuleDocstring | Private method to extract a docstring given a module source.
__parseTopLevel | Private method to extract top-level functions or classes.
__readline | Private method to get the next line from the source.
__resetReadline | Private method to reset the internal readline function.
__skipIndentedBlock | Private method to skip over an indented block of source code.
addError | Public method to record an issue.
run | Public method to check the given source for violations of doc string conventions.

### Static Methods

None

#### DocStyleChecker (Constructor)

DocStyleChecker(source, filename, select, ignore, expected, repeat, maxLineLength=88, docType="pep257", )

Constructor

source (list of str)
  source code to be checked
filename (str)
  name of the source file
select (list of str)
  list of selected codes
ignore (list of str)
  list of codes to be ignored
expected (list of str)
  list of expected codes
repeat (bool)
  flag indicating to report each occurrence of a code
maxLineLength (int)
  allowed line length
docType (str)
  type of the documentation strings (one of 'eric' or 'pep257')

#### DocStyleChecker.__checkBackslashes

__checkBackslashes(docstringContext, _context)

Private method to check, that all docstrings containing backslashes are surrounded by raw triple double quotes.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkBlankAfterLastParagraph

__checkBlankAfterLastParagraph(docstringContext, _context)

Private method to check, that the last paragraph of docstrings is followed by a blank line.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkBlankAfterSummary

__checkBlankAfterSummary(docstringContext, _context)

Private method to check, that docstring summaries are followed by a blank line.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkBlankBeforeAndAfterClass

__checkBlankBeforeAndAfterClass(docstringContext, context)

Private method to check, that class docstrings have one blank line around them.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkClassDocstring

__checkClassDocstring(docstringContext, context)

Private method to check, that all public functions and methods have a docstring.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkEndsWithPeriod

__checkEndsWithPeriod(docstringContext, _context)

Private method to check, that docstring summaries end with a period.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkEricBlankAfterSummary

__checkEricBlankAfterSummary(docstringContext, _context)

Private method to check, that docstring summaries are followed by a blank line.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkEricDocumentationDeprecatedTags

__checkEricDocumentationDeprecatedTags(docstringContext, _context, )

Private method to check the use of deprecated documentation tags.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkEricDocumentationIndent

__checkEricDocumentationIndent(docstringContext, _context, )

Private method to check the the correct indentation of the tag lines.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkEricDocumentationSequence

__checkEricDocumentationSequence(docstringContext, _context, )

Private method to check, that method docstring follows the correct sequence of entries (e.g. @param is followed by @type).

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkEricEndsWithPeriod

__checkEricEndsWithPeriod(docstringContext, _context)

Private method to check, that docstring summaries end with a period.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkEricException

__checkEricException(docstringContext, context)

Private method to check, that docstrings contain an @exception line if they raise an exception and don't otherwise.

Note: This method also checks the raised and documented exceptions for completeness (i.e. raised exceptions that are not documented or documented exceptions that are not raised)

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkEricFunctionArguments

__checkEricFunctionArguments(docstringContext, context)

Private method to check, that docstrings contain an @param and/or @keyparam line for each argument.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkEricNBlankAfterLastParagraph

__checkEricNBlankAfterLastParagraph(docstringContext, _context)

Private method to check, that the last paragraph of docstrings is not followed by a blank line.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkEricNoBlankBeforeAndAfterClassOrFunction

__checkEricNoBlankBeforeAndAfterClassOrFunction(docstringContext, context)

Private method to check, that class and function/method docstrings have no blank line around them.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkEricQuotesOnSeparateLines

__checkEricQuotesOnSeparateLines(docstringContext, _context)

Private method to check, that leading and trailing quotes are on a line by themselves.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkEricReturn

__checkEricReturn(docstringContext, context)

Private method to check, that docstrings contain an @return line if they return anything and don't otherwise.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkEricSignal

__checkEricSignal(docstringContext, context)

Private method to check, that docstrings contain an @signal line if they define signals and don't otherwise.

Note: This method also checks the defined and documented signals for completeness (i.e. defined signals that are not documented or documented signals that are not defined)

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkEricSummary

__checkEricSummary(docstringContext, context)

Private method to check, that method docstring summaries start with specific words.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkEricYield

__checkEricYield(docstringContext, context)

Private method to check, that docstrings contain an @yield line if they return anything and don't otherwise.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkFunctionDocstring

__checkFunctionDocstring(docstringContext, context)

Private method to check, that all public functions and methods have a docstring.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkImperativeMood

__checkImperativeMood(docstringContext, _context)

Private method to check, that docstring summaries are in imperative mood.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkIndent

__checkIndent(docstringContext, context)

Private method to check, that docstrings are properly indented.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkModulesDocstrings

__checkModulesDocstrings(docstringContext, context)

Private method to check, if the module has a docstring.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkNoBlankLineBefore

__checkNoBlankLineBefore(docstringContext, context)

Private method to check, that function/method docstrings are not preceded by a blank line.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkNoSignature

__checkNoSignature(docstringContext, context)

Private method to check, that docstring summaries don't repeat the function's signature.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkOneLiner

__checkOneLiner(docstringContext, context)

Private method to check, that one-liner docstrings fit on one line with quotes.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkReturnType

__checkReturnType(docstringContext, context)

Private method to check, that docstrings mention the return value type.

docstringContext (DocStyleContext)
  docstring context
context (DocStyleContext)
  context of the docstring

#### DocStyleChecker.__checkSummary

__checkSummary(docstringContext, _context)

Private method to check, that docstring summaries contain some text.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__checkTripleDoubleQuotes

__checkTripleDoubleQuotes(docstringContext, _context)

Private method to check, that all docstrings are surrounded by triple double quotes.

docstringContext (DocStyleContext)
  docstring context
_context (DocStyleContext)
  context of the docstring (unused)

#### DocStyleChecker.__getArgNames

__getArgNames(node)

Private method to get the argument names of a function node.

node (ast.AST)
  AST node to extract arguments names from

Return:
  tuple of two list of argument names, one for arguments and one for keyword arguments

Return Type:
  tuple of (list of str, list of str)

#### DocStyleChecker.__getSummaryLine

__getSummaryLine(docstringContext)

Private method to extract the summary line.

docstringContext (DocStyleContext)
  docstring context

Return:
  summary line (string) and the line it was found on

Return Type:
  int

#### DocStyleChecker.__getSummaryLines

__getSummaryLines(docstringContext)

Private method to extract the summary lines.

docstringContext (DocStyleContext)
  docstring context

Return:
  summary lines (list of string) and the line it was found on

Return Type:
  int

#### DocStyleChecker.__parseClasses

__parseClasses()

Private method to extract top-level classes.

Return:
  extracted class contexts

Return Type:
  list of DocStyleContext

#### DocStyleChecker.__parseContexts

__parseContexts(kind)

Private method to extract a context from the source.

kind (str)
  kind of context to extract

Return:
  requested contexts

Return Type:
  list of DocStyleContext

#### DocStyleChecker.__parseDocstring

__parseDocstring(context, what="")

Private method to extract a docstring given `def` or `class` source.

context (DocStyleContext)
  context data to get the docstring from
what (str)
  string denoting what is being parsed

Return:
  context of extracted docstring

Return Type:
  DocStyleContext

#### DocStyleChecker.__parseFunctions

__parseFunctions()

Private method to extract top-level functions.

Return:
  extracted function contexts

Return Type:
  list of DocStyleContext

#### DocStyleChecker.__parseMethods

__parseMethods()

Private method to extract methods of all classes.

Return:
  extracted method contexts

Return Type:
  list of DocStyleContext

#### DocStyleChecker.__parseModuleDocstring

__parseModuleDocstring(source)

Private method to extract a docstring given a module source.

source (list of str)
  source to parse

Return:
  context of extracted docstring

Return Type:
  DocStyleContext

#### DocStyleChecker.__parseTopLevel

__parseTopLevel(keyword)

Private method to extract top-level functions or classes.

keyword (str)
  keyword signaling what to extract

Return:
  extracted function or class contexts

Return Type:
  list of DocStyleContext

#### DocStyleChecker.__readline

__readline()

Private method to get the next line from the source.

Return:
  next line of source

Return Type:
  str

#### DocStyleChecker.__resetReadline

__resetReadline()

Private method to reset the internal readline function.

#### DocStyleChecker.__skipIndentedBlock

__skipIndentedBlock(tokenGenerator)

Private method to skip over an indented block of source code.

tokenGenerator (str iterator)
  token generator

Return:
  last token of the indented block

Return Type:
  tuple

#### DocStyleChecker.addError

addError(lineNumber, offset, msgCode, *args)

Public method to record an issue.

lineNumber (int)
  line number of the issue (zero based)
offset (int)
  position within line of the issue
msgCode (str)
  message code
args (list)
  arguments for the message

#### DocStyleChecker.run

run()

Public method to check the given source for violations of doc string conventions.

Up

## DocStyleContext

Class implementing the source context.

### Derived from

None

### Class Attributes

None

### Class Methods

None

### Methods

DocStyleContext | Constructor
contextType | Public method to get the context type.
end | Public method to get the end line number.
indent | Public method to get the indentation of the first line.
setSpecial | Public method to set a special attribute for the context.
source | Public method to get the source.
special | Public method to get the special context attribute string.
ssource | Public method to get the joined source lines.
start | Public method to get the start line number.

### Static Methods

None

#### DocStyleContext (Constructor)

DocStyleContext(source, startLine, contextType)

Constructor

source (list of str or str)
  source code of the context
startLine (int)
  line number the context starts in the source
contextType (str)
  type of the context object

#### DocStyleContext.contextType

contextType()

Public method to get the context type.

Return:
  context type

Return Type:
  str

#### DocStyleContext.end

end()

Public method to get the end line number.

Return:
  end line number

Return Type:
  int

#### DocStyleContext.indent

indent()

Public method to get the indentation of the first line.

Return:
  indentation string

Return Type:
  str

#### DocStyleContext.setSpecial

setSpecial(special)

Public method to set a special attribute for the context.

special (str)
  attribute string

#### DocStyleContext.source

source()

Public method to get the source.

Return:
  source

Return Type:
  list of str

#### DocStyleContext.special

special()

Public method to get the special context attribute string.

Return:
  attribute string

Return Type:
  str

#### DocStyleContext.ssource

ssource()

Public method to get the joined source lines.

Return:
  source

Return Type:
  str

#### DocStyleContext.start

start()

Public method to get the start line number.

Return:
  start line number

Return Type:
  int

Up